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A Quick Reference for The Debugger V2 - 1/4/93 © Steve Jasik 1993 


Installation Procedure 
Debugger Tech Note #0 is the guide to installing The Debugger, read it. 


Multiple Monitor Operation 


Mac II, etc - Debugger takes over the startup Screen. Option-Monitors in Control Panels to set. 
In Monitors, drag the little Mac Icon to the Monitor that you want The Debugger to appear on. 


RunDbgr versus XDbgr_Startup 


Support for RunDbgr is being phased out as it has no use in System 7. 

You need at least 4 Meg of RAM to run The Debugger in the background and 8 Meg or more is 
preferred to get any real work done. You can NOT Launch The Debugger after MultiFinder. 
You may change the name of xDbgr_Startup so that it loads earlier in the INIT load sequence. 
xDber_Startup “launchs" a file by the name of "The Debugger ", so do not change it. 


Macsbug, INITs and Other Gotchas 
The Macsbug in “put files in System folder” installs itself in high memory and records patches to the 
Traps until the Finder is launched. It uses 8K of memory. To see who patched the Traps, check out the 
“ROM Patch Info” command in the Display menu. 
You may install Apple’s Macsbug as Macsbug, and rename my Macsbug to “Disassembler’. 
When The Debugger starts up it makes a copy of the “low memory globals” (trap vectors, etc.) so that it 
will not be affected by patches to the traps that are set by programs that come after it. 

The Debugger is not compatible with all INITs. See Debugger Tech Note 0 for details. 

To avoid interference between the command-option key equivalents in QuicKeys™ and those in The 
Debugger, you may wish to rename QuicKeys™ to zQuicKeys™ . 


Menus and Commands, General 


Command-option key equivalents show up as Omega-Key (Q) in the Menus. 
When the key equivalent is a lower case letter, Shift-Command-letter will result in a different 
function (Cmd-B is a simple Bkpt, Shift-Cmd-B is a Bkpt with the current action clause attached to it.) 


Some unshifted/shifted menu items options are presented in the menu in the format 
“unshifted/SHIFTED command.” For example, in the Tables menu, the first menu item is 
Record/ALL names, which lists all the known type names if the shift key is held down, 
and only the built in Record names if is not. 


Menu items that are check items show up in Bold face; a check mark indicates it is selected. 
Many commands check for a selection in the front window, and will use it if present. 
Pressing the ‘esc’ key will clear any selection in the front window. 


If nothing is selected, then the command will bring up a simple type in dialog box just below the menu 
bar. You can paste into these dialogs with Cmd-V; and dismiss them with a Cmd-period. 
Clicking in the “Cmd?” box is equivalent to a return. 


Use Cmd-period to abort a command or stop continuous Step mode, etc. 
The first item in the menu bar is the amount of free space in The Debugger’s Heap zone. 
The first menu contains a Help command. 


The Find command - Searching for Text in a Window 


If some object is selected in the front window, then the Find command (Cmd-F) accepts it as the search 
pattern and looks for the next occurrence of it as a token (separated by delimiters). 


If nothing is hilited in the front window, then it brings up the find dialog window . 


An alternate way to a search for a pattern (case insensitive, no delimiters) is to copy a string (Cmd-C) 
and then Cmd-G. 


Windows & Tasks, General 


All windows (not dialogs) use a custom text editor that supports the display of large files, tabs and 
Undo/Redo. It's behavior is similar to that of the MPW Shell editor. 

Cmd-delete deletes to the end of file. Triple clicking will hilight a line, and double clicking on a left 
paren {‘(, ‘t, ‘TZ ) or quote mark, etc will hilight to the matching right paren, etc. 

Use Option-Click to obtain a popup menu of the windows to bring one to the front. 

In The Debugger most of the windows are read only. You can copy from them. 


A quick way of transferring a selection to the “-Notes-” window is to use Cmd-N. 


Windows that are task relative are prefixed with “dtaskname.” 

A task is a process (APPL or executable resource). The list of tasks known to The Debugger is 
displayed in the “-Task & File Info-” window (Q-T) along with the list of open files. 

The last item in the Menu bar is the number and name of the task you are in. It will change as you 
switch from one task relative window to another. Commands that are task relative (such as display 
Code! Data block) will search tables, etc. relative to that task. 


To debug a task symbolically you must prepare an auxiliary file that contains symbol information 
that resides in the same folder from which the task will be executed. 

The aux file may be: a Nosy “snt” file, an MPW or MDS style “map” file, an MPW V3.x “SYM” file 
or the Think C PROJ file itself (see page 32 of The Debugger manual). 


Debugger, Entry/Exit 

Cmd-E to exit The Debugger . 

To enter The Debugger, press Option-\ or the Programmers Switch, or press Cmd-PowerKey if you are 
using the Programmer's Key INIT. 


When in The Debugger, use the ~ (tilde) key to view the PP’s screen (swap screen mode). 


On Entry to The Debugger from the PP 


On a context switch into it, The Debugger puts one or more lines into the “-Notes-” window to show 
why you entered it, updates the “-Registers-” and “-Stack State-” windows, and a window of the 
procedure containing a disassembly (or source) of the current PC. 

The menubar task indicator is set to the task of the procedure containing the PC. 

To reset the display to the current PC, hilite the value of the PC in -Registers- and Cmd-D. 


Source Level Debugging (MPW V3.x .SYM file or Think C™ project) 


For a Think C project, the source files must be on the same volume as the “project” file, 
while with MPW “.SYM?” files, the path to the source is specified in a “.dsi” file (DTN #3). 


Use the “Source only windows” command (N-V) to set the default mode of display. 
The first line of the window gives the name of the file containing the source of the procedure. 
Use a Command-click (mouse down) to toggle a window between Source only and source with 


interspersed assembly. In the source only windows, a”>7” in column 1 denotes the beginning of a 
statement. In LightSpeedC Compile with "Use Debugger’ on and run with it OFF. 


Displaying procedures 

Hilite the name of a proc and Cmd-D, or Cmd-D with nothing hilited and you will get a type-in dialog 
box. Typing in the leading characters of a procedure name will result in a window with a list of names 
that match, or one with code of the procedure if the leading chars only matched on one name, 

More often in The Debugger, you want to look at an active proc, i.e. one that is in the call chain. 
Activate the “-Stack State-” window, find the proc you want, hilite the “=nnn” and Cmd-D. Not only is 
this slightly faster, but it also switches The Debugger to the task the proc is in and positions the 
selection to the point of the call. 


Breakpoints 


To set or clear a breakpoint, hilite a line in a procedure window and Cmd-B. 
To attach the current “action clause” to a breakpoint, Shift-Cmd-B. 


To define an “action clause”, hilite it and 2-B. It will become the current “action clause”. 


To change the current “action clause”, de-hilite any selection in the front window and Q-B. 
Then enter the number of the “action clause” you wish to make current. 


To delete an “action clause”. de-hilite any selection in the front window and Shift-Q-B. 
Then enter the number of the “action clause” you wish to delete. 


Do not set a breakpoint in ROM patch code that The Debugger may execute! 
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In Application: 
Option-\ 


In Debugger: 
Q 
Æ -. or ESC 
#-D 
2 -W 
3 -Space 
Shift- -U 
Q-U 


Debugger Cheat Sheet 


Rev 6/11/95 


Break into Debugger (after _WNE/_GNE) 


( if a code window is frontmost, then % key is optional) 


option and % keys both heid down 


Abort/cancel current command, dialog, etc 
Toggle to view user's screen 


Display (hilited) Procedure 
Display (hilited) variable value (global or local) 
Display data value of memory (type_@nnnn, ...) 


Display Local vars Window (all active procs) 
Display Local vars Window (current proc) 


click on Pencil Box in Window Title to enable type-over of data values 


3-8 

3% -B 

Q-B 
Shift- -B 
Q-W 

Q-P 

# -E 

%-, 

% -? 

96 -; 


æ -H 

Q-G 

Q-T 

%& -[ 
Shift-3 -[ 
-minus 
Q-F 

J -m 
Shift-% -= 
Q-2 


Set/clear breakpoint on hilited line 
Define or rémove a Breakpoint “action clause” 


Set breakpoint with current action clause attached 
Set/clear Watchpoint (memory change) 
Go (execute) until hilited line is reached 


Exit to program 

Step over current line of code 

Step into current line of code 

Step continuous (3% key down to pause, 3-period to stop) 


Display Current Heap Zone (shift-3-H for System heap) 
Find the heap zone and block containing a given address 
display list of Tasks, open Rsrc files, Open files 

Expression Calculator - evaluate the value of an ‘expression’ 
Execute “block of statements” or a procedure call or DCMD 


Convert Hilited Hex number to decimal 
Execute hilited ".dsi" file command 


Unstructured dump of 68K code 


Unstructured dump of PowerPC code 
Side Door to Shell (MPW or ObjectMaster™) 


Macsbug 
Equiv 


dm 


Toggle window for dynamic update (%-space & Values windows) 


br 


ss 


so 


wh 


in a Source code window: 
To Setclear breakpoint move the cursor to the left edge and it will change 
to a STOP sign with a bullet in the center. Clicking the mouse will toggle a Breakpoint. 


Holding down the % key and clicking the mouse button will toggle between 
a source code only and source with assembly interspersed. 


Anywhere: 
To get a Popup Menu of the list of windows, hold down the Option key 
and press the Mouse button. 


To Toggle a Debugger Flag: 
Double-click on the flag Name in the ‘-Dbgr Status- window. 


To reset the hilited line to the current value of the PC (Program counter): 
Doubie-click on the VALUE of the PC in the ‘-Registers-’ window and %-D 


in MPW Shell (IBS commands): 
Opt-36-Z Hint hilited procedure 
Opt-%-B Patch Link 
Opt-36-P Show IBS project Status 


Cmd-Option-Click processing 

In a Source code window: 

Hilite a name and -click will produce a Popup Menu with the choices 
Display as a Procedure (#-D) or as a Variable (3¢-W) 


In all other windows Q-clicking on an address or “type@address” 
OR in the title bar of a “type@address” window 

will produce a ‘View as’ Popup Menu which will let you cast the 
address to the type you want. 

Types below the default type may be set via the ‘.dsi’ command: 


=X define types in ‘View As’ - one per line or comma seperated list 
RoutineDescriptor 

ParamBlockRec 

Fixed, Cstring 


